<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="ctypes-data-types.html" />
<link rel="prev" href="ctypes-function-prototypes.html" />
<link rel="parent" href="ctypes-ctypes-reference.html" />
<link rel="next" href="ctypes-data-types.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>14.14.2.5 Utility functions</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="14.14.2.4 function prototypes"
  href="ctypes-function-prototypes.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="14.14.2 ctypes reference"
  href="ctypes-ctypes-reference.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="14.14.2.6 data types"
  href="ctypes-data-types.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="ctypes-function-prototypes.html">14.14.2.4 Function prototypes</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="ctypes-ctypes-reference.html">14.14.2 ctypes reference</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="ctypes-data-types.html">14.14.2.6 Data types</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h3><a name="SECTION00161425000000000000000"></a><a name="ctypes-utility-functions"></a>
<br>
14.14.2.5 Utility functions
</h3>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3327' xml:id='l2h-3327' class="function">addressof</tt></b>(</nobr></td>
  <td><var>obj</var>)</td></tr></table></dt>
<dd>
Returns the address of the memory buffer as integer.  <code>obj</code> must
be an instance of a ctypes type.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3328' xml:id='l2h-3328' class="function">alignment</tt></b>(</nobr></td>
  <td><var>obj_or_type</var>)</td></tr></table></dt>
<dd>
Returns the alignment requirements of a ctypes type.
<code>obj_or_type</code> must be a ctypes type or instance.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3329' xml:id='l2h-3329' class="function">byref</tt></b>(</nobr></td>
  <td><var>obj</var>)</td></tr></table></dt>
<dd>
Returns a light-weight pointer to <code>obj</code>, which must be an
instance of a ctypes type. The returned object can only be used as
a foreign function call parameter. It behaves similar to
<code>pointer(obj)</code>, but the construction is a lot faster.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3330' xml:id='l2h-3330' class="function">cast</tt></b>(</nobr></td>
  <td><var>obj, type</var>)</td></tr></table></dt>
<dd>
This function is similar to the cast operator in C. It returns a
new instance of <code>type</code> which points to the same memory block as
<code>obj</code>. <code>type</code> must be a pointer type, and <code>obj</code> must be an
object that can be interpreted as a pointer.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3331' xml:id='l2h-3331' class="function">create_string_buffer</tt></b>(</nobr></td>
  <td><var>init_or_size</var><big>[</big><var>, size</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This function creates a mutable character buffer. The returned
object is a ctypes array of <tt class="class">c_char</tt>.

<p>
<code>init_or_size</code> must be an integer which specifies the size of
the array, or a string which will be used to initialize the array
items.

<p>
If a string is specified as first argument, the buffer is made one
item larger than the length of the string so that the last element
in the array is a NUL termination character. An integer can be
passed as second argument which allows to specify the size of the
array if the length of the string should not be used.

<p>
If the first parameter is a unicode string, it is converted into
an 8-bit string according to ctypes conversion rules.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3332' xml:id='l2h-3332' class="function">create_unicode_buffer</tt></b>(</nobr></td>
  <td><var>init_or_size</var><big>[</big><var>, size</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This function creates a mutable unicode character buffer. The
returned object is a ctypes array of <tt class="class">c_wchar</tt>.

<p>
<code>init_or_size</code> must be an integer which specifies the size of
the array, or a unicode string which will be used to initialize
the array items.

<p>
If a unicode string is specified as first argument, the buffer is
made one item larger than the length of the string so that the
last element in the array is a NUL termination character. An
integer can be passed as second argument which allows to specify
the size of the array if the length of the string should not be
used.

<p>
If the first parameter is a 8-bit string, it is converted into an
unicode string according to ctypes conversion rules.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3333' xml:id='l2h-3333' class="function">DllCanUnloadNow</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Windows only: This function is a hook which allows to implement
inprocess COM servers with ctypes. It is called from the
DllCanUnloadNow function that the _ctypes extension dll exports.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3334' xml:id='l2h-3334' class="function">DllGetClassObject</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Windows only: This function is a hook which allows to implement
inprocess COM servers with ctypes. It is called from the
DllGetClassObject function that the <code>_ctypes</code> extension dll exports.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3335' xml:id='l2h-3335' class="function">FormatError</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>code</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Windows only: Returns a textual description of the error code. If
no error code is specified, the last error code is used by calling
the Windows api function GetLastError.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3336' xml:id='l2h-3336' class="function">GetLastError</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Windows only: Returns the last error code set by Windows in the
calling thread.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3337' xml:id='l2h-3337' class="function">memmove</tt></b>(</nobr></td>
  <td><var>dst, src, count</var>)</td></tr></table></dt>
<dd>
Same as the standard C memmove library function: copies <var>count</var>
bytes from <code>src</code> to <var>dst</var>. <var>dst</var> and <code>src</code> must be
integers or ctypes instances that can be converted to pointers.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3338' xml:id='l2h-3338' class="function">memset</tt></b>(</nobr></td>
  <td><var>dst, c, count</var>)</td></tr></table></dt>
<dd>
Same as the standard C memset library function: fills the memory
block at address <var>dst</var> with <var>count</var> bytes of value
<var>c</var>. <var>dst</var> must be an integer specifying an address, or a
ctypes instance.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3339' xml:id='l2h-3339' class="function">POINTER</tt></b>(</nobr></td>
  <td><var>type</var>)</td></tr></table></dt>
<dd>
This factory function creates and returns a new ctypes pointer
type. Pointer types are cached an reused internally, so calling
this function repeatedly is cheap. type must be a ctypes type.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3340' xml:id='l2h-3340' class="function">pointer</tt></b>(</nobr></td>
  <td><var>obj</var>)</td></tr></table></dt>
<dd>
This function creates a new pointer instance, pointing to
<code>obj</code>. The returned object is of the type POINTER(type(obj)).

<p>
Note: If you just want to pass a pointer to an object to a foreign
function call, you should use <code>byref(obj)</code> which is much faster.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3341' xml:id='l2h-3341' class="function">resize</tt></b>(</nobr></td>
  <td><var>obj, size</var>)</td></tr></table></dt>
<dd>
This function resizes the internal memory buffer of obj, which
must be an instance of a ctypes type. It is not possible to make
the buffer smaller than the native size of the objects type, as
given by sizeof(type(obj)), but it is possible to enlarge the
buffer.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3342' xml:id='l2h-3342' class="function">set_conversion_mode</tt></b>(</nobr></td>
  <td><var>encoding, errors</var>)</td></tr></table></dt>
<dd>
This function sets the rules that ctypes objects use when
converting between 8-bit strings and unicode strings. encoding
must be a string specifying an encoding, like <code>'utf-8'</code> or
<code>'mbcs'</code>, errors must be a string specifying the error handling
on encoding/decoding errors. Examples of possible values are
<code>"strict"</code>, <code>"replace"</code>, or <code>"ignore"</code>.

<p>
<code>set_conversion_mode</code> returns a 2-tuple containing the previous
conversion rules. On windows, the initial conversion rules are
<code>('mbcs', 'ignore')</code>, on other systems <code>('ascii', 'strict')</code>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3343' xml:id='l2h-3343' class="function">sizeof</tt></b>(</nobr></td>
  <td><var>obj_or_type</var>)</td></tr></table></dt>
<dd>
Returns the size in bytes of a ctypes type or instance memory
buffer. Does the same as the C <code>sizeof()</code> function.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3344' xml:id='l2h-3344' class="function">string_at</tt></b>(</nobr></td>
  <td><var>address</var><big>[</big><var>, size</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This function returns the string starting at memory address
address. If size is specified, it is used as size, otherwise the
string is assumed to be zero-terminated.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3345' xml:id='l2h-3345' class="function">WinError</tt></b>(</nobr></td>
  <td><var>code=None, descr=None</var>)</td></tr></table></dt>
<dd>
Windows only: this function is probably the worst-named thing in
ctypes. It creates an instance of WindowsError. If <var>code</var> is not
specified, <code>GetLastError</code> is called to determine the error
code. If <code>descr</code> is not spcified, <tt class="function">FormatError</tt> is called to
get a textual description of the error.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3346' xml:id='l2h-3346' class="function">wstring_at</tt></b>(</nobr></td>
  <td><var>address</var>)</td></tr></table></dt>
<dd>
This function returns the wide character string starting at memory
address <code>address</code> as unicode string. If <code>size</code> is specified,
it is used as the number of characters of the string, otherwise
the string is assumed to be zero-terminated.
</dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="14.14.2.4 function prototypes"
  href="ctypes-function-prototypes.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="14.14.2 ctypes reference"
  href="ctypes-ctypes-reference.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="14.14.2.6 data types"
  href="ctypes-data-types.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="ctypes-function-prototypes.html">14.14.2.4 Function prototypes</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="ctypes-ctypes-reference.html">14.14.2 ctypes reference</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="ctypes-data-types.html">14.14.2.6 Data types</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
